.\"
.\" Copyright (c) 2015-2018 The heketi Authors
.\"
.\" This file is licensed to you under your choice of the GNU Lesser
.\" General Public License, version 3 or any later version (LGPLv3 or
.\" later), or the GNU General Public License, version 2 (GPLv2), in all
.\" cases as published by the Free Software Foundation.
.\"
.TH heketi-cli 8 "Heketi command line program" "Apr 2016" "The heketi Authors"
.nh
.ad l
.SH NAME
.PP
heketi\-cli \- Command line program for Heketi
.SH SYNOPSIS
.PP
\fBheketi\-cli\fP [commands] [options]
.SH DESCRIPTION
.PP
Command line program for Heketi
.SH COMMANDS
.SS "Cluster Commands"
.PP
.B heketi\-cli cluster create [\-\-file[=false]] [\-\-block[=false]]
.RS
Create a cluster
.PP
.B Options
.RS
.TP
\fB\-\-file\fP[=false]
Optional:
Allow the user to control the possibility of creating regular file volumes on the cluster to be created.
This is enabled by default.
Use '\-\-file=false' to disable creation of regular file volumes on this cluster.
(default true)
.TP
\fB\-\-block\fP[=false]
Optional:
Allow the user to control the possibility of creating block volumes on the cluster to be created.
This is enabled by default.
Use '\-\-block=false' to disable creation of block volumes on this cluster.
(default true)
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli cluster create \-\-block=false
.fi
.RE
.RE
.PP
.B heketi\-cli cluster setflags [\-\-file=true|false] [\-\-block=true|false] <Cluster-ID>
.RS
Set file and block flags on a cluster.
.PP
.B Options
.RS
.TP
\fB\-\-file\fP=true|false
Optional:
Allow the user to control the possibility of creating regular file volumes on the cluster.
Use '\-\-file=true' to enable and '\-\-file=false' to disable creation of regular file volumes on this cluster.
.TP
\fB\-\-block\fP=true|false
Optional:
Allow the user to control the possibility of creating block volumes on the cluster.
Use '\-\-block=true' to enable and '\-\-block=false' to disable creation of block volumes on this cluster.
.RE
.PP
.B Example
.RS
.nf
$ heketi\-cli cluster setflags \-\-block=false 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli cluster delete <CLUSTER-ID>\fP
.RS
Delete a cluster
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli cluster delete 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli cluster info  <CLUSTER-ID>\fP
.RS
Retrieves information about cluster
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli cluster info 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli cluster list\fP
.RS
Lists the clusters managed by Heketi
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli cluster list
.fi
.RE
.RE
.SS "Device Commands"
.PP
\fBheketi\-cli device add \-\-name=<DEVICE-NAME> \-\-node=<NODE-ID>\fP
.RS
Add new device to node to be managed by Heketi
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-name\fP=""
Name of device to add
.TP
\fB\-\-node\fP=""
Id of the node which has this device
.TP
\fB\-\-destroy-existing-data
Optional:
Destroy existing data on the device (DANGEROUS).
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli device add \\
    \-\-name=/dev/sdb \\
    \-\-node=3e098cb4407d7109806bb196d9e8f095
.fi
.RE
.RE
.PP
\fBheketi\-cli device delete <DEVICE-ID>\fP
.RS
Deletes a device from Heketi node
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-force-forget
Optional:
Remove the device from heketi regardless of it's state on the node (DANGEROUS).
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device delete 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device disable <DEVICE\-ID>\fP
.RS
Disallow usage of a device by placing it offline
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli device disable 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device enable <DEVICE\-ID>\fP
.RS
Allows device to go online
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli device enable 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device info  <DEVICE-ID>\fP
.RS
Retrieves information about device
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device info 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device remove  <DEVICE-ID>\fP
.RS
Moves a device to removed/failed state, replacing all its bricks by bricks on other devices. This requires the device to be brought to disabled/offline state first.
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device remove 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device resync <DEVICE-ID>\fP
.RS
Resync storage information about the device with operation system
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device resync 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli device settags <DEVICE-ID> <TAG>:<VALUE> ...\fP
.RS
Set metadata tags on a given device. Tags are free-form key value pairs
that are stored by Heketi and may be used for extra configuration.
One or more <TAG>:<TAG-VALUE> pairs may be provided.
.PP
.B Options
.RS
.TP
\fB\-\-exact
Optional:
Overwrite the existing tags with the exactly set of tags (and values)
specified on this command line. Without this option, the command will
add or update tags.
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device settags 886a86a868711bef83001 arbiter:required flavor:strawberry
.fi
.RE
.RE
.PP
\fBheketi\-cli device rmtags <DEVICE-ID> <TAG> ...\fP
.RS
Remove metadata tags from a given device.
.PP
.B Options
.RS
.TP
\fB\-\-all
Optional:
Remove all tags from the specified device. May not be combined with
specifying tag names.
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli device rmtags 886a86a868711bef83001 arbiter
.fi
.RE
.RE
.SS "Node Commands"
.PP
\fBheketi\-cli node add \-\-zone=<ZONE-NUMBER> \-\-cluster=<CLUSTER-ID> \-\-management\-host\-name=<MANAGEMENT-HOSTNAME> \-\-storage-host-name=<STORAGE-HOSTNAME>\fP
.RS
Add new node to be managed by Heketi
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-cluster\fP=""
The cluster in which the node should reside
.TP
\fB\-\-management\-host\-name\fP=""
Management host name
.TP
\fB\-\-storage\-host\-name\fP=""
Storage host name
.TP
\fB\-\-zone\fP=\-1
The zone in which the node should reside
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli node add \\
    \-\-zone=3 \\
    \-\-cluster=3e098cb4407d7109806bb196d9e8f095 \\
    \-\-management\-host\-name=node1\-manage.gluster.lab.com \\
    \-\-storage\-host\-name=node1\-storage.gluster.lab.com
.fi
.RE
.RE
.PP
\fBheketi\-cli node delete <NODE-ID>\fP
.RS
Deletes a node from Heketi management
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli node delete 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli node disable <NODE\-ID>\fP
.RS
Disallow usage of a node by placing it offline
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli node disable 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli node enable <NODE\-ID>\fP
.RS
Allows node to go online
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli node enable 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli node info  <NODE-ID>\fP
.RS
Retrieves information about node
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli node info 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli node list\fP
.RS
List all nodes in cluster
.PP
\fBExample\fP
.RE
.nf
$ heketi\-cli node list
.fi
.RE
.RE
.PP
\fBheketi\-cli node settags <NODE-ID> <TAG>:<VALUE> ...\fP
.RS
Set metadata tags on a given node. Tags are free-form key value pairs
that are stored by Heketi and may be used for extra configuration.
One or more <TAG>:<TAG-VALUE> pairs may be provided.
.PP
.B Options
.RS
.TP
\fB\-\-exact
Optional:
Overwrite the existing tags with the exactly set of tags (and values)
specified on this command line. Without this option, the command will
add or update tags.
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli node settags 886a86a868711bef83001 arbiter:required flavor:strawberry
.fi
.RE
.RE
.PP
\fBheketi\-cli node rmtags <NODE-ID> <TAG> ...\fP
.RS
Remove metadata tags from a given node.
.PP
.B Options
.RS
.TP
\fB\-\-all
Optional:
Remove all tags from the specified node. May not be combined with
specifying tag names.
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli node rmtags 886a86a868711bef83001 arbiter
.fi
.RE
.RE
.SS "Setup OpenShift/Kubernetes persistent storage for Heketi"
.PP
\fBheketi\-cli setup\-openshift\-heketi\-storage\fP
.RS
Creates a dedicated GlusterFS volume for Heketi.
Once the volume is created, a Kubernetes/OpenShift
list object is created to configure the volume.
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-listfile\fP="heketi\-storage.json"
Filename to contain list of objects
.TP
\fB\-\-listfile\fP="heketi\-storage.json"
Filename to contain list of objects
.TP
\fB\-\-durability\fP="replicate"
Optional: Durability type.
Values are:
.RS
.TP
none: No durability, for testing with single storage server environments.
.TP
replicate: (Default) Replica volume.
.RE
.TP
\fB\-\-replica\fP=3
Replica value for durability type 'replicate'.
Default is 3
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi\-cli setup\-openshift\-heketi\-storage
.fi
.RE
.RE
.PP
.SS "Topology Commands"
.PP
\fBheketi\-cli topology load \-\-json=<JSON-FILENAME>\fP
.RS
Add devices to Heketi from a configuration file
.PP
\fB           Options\fP
.RS
.TP
\fB\-j, \-\-json\fP=""
Configuration containing devices, nodes, and clusters, in JSON format
.RE
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli topology load --json=topo.json
.fi
.RE
.RE
.PP
\fBheketi\-cli topology info \fP
.RS
Retreives information about the current Topology
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli topology info
.fi
.RE
.RE
.SS "Volume Commands"
.PP
\fBheketi\-cli volume create \-\-clusters=<CLUSTER-IDS> \-\-disperse-data=<DISPERSION-VALUE> \-\-durability=<TYPE> \-\-name=<VOLUME-NAME> \-\-redundancy=<REDUNDENCY-VALUE> \-\-replica=<REPLICA-VALUE> \-\-size=<VOLUME-SIZE> \-\-snapshot-factor=<SNAPSHOT-FACTOR-VALUE>\fP
.RS
Create a GlusterFS volume
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-clusters\fP=""
Optional: Comma separated list of cluster ids where this volume must be allocated.
If omitted, Heketi will allocate the volume on any of the configured clusters which have the available space.
Providing a set of clusters will ensure Heketi allocates storage for this volume only in the clusters specified.
.TP
\fB\-\-disperse\-data\fP=4
Optional: Dispersion value for durability type 'disperse'.
Default is 4
.TP
\fB\-\-durability\fP="replicate"
Optional: Durability type.
Values are:
.RS
.TP
none: No durability. Distributed volume only.
.TP
replicate: (Default) Distributed\-Replica volume.
.TP
disperse: Distributed\-Erasure Coded volume.
.RE
.TP
\fB\-\-gid\fP=0
Optional: Initialize volume with the specified group id.
Default is 0.
.TP
\fB\-\-name\fP=""
Optional: Name of volume. Only set if really necessary
.TP
\fB\-\-persistent\-volume\fP[=false]
Optional: Output to standard out a persistent volume JSON file for OpenShift or
Kubernetes with the name provided.
.TP
\fB\-\-persistent\-volume\-endpoint\fP=""
Optional: Endpoint name for the persistent volume
.TP
\fB\-\-persistent\-volume\-file\fP=""
Optional: Create a persistent volume JSON file for OpenShift or
Kubernetes with the name provided.
.TP
\fB\-\-redundancy\fP=2
Optional: Redundancy value for durability type 'disperse'.
Default is 2.
.TP
\fB\-\-replica\fP=3
Replica value for durability type 'replicate'.
Default is 3.
.TP
\fB\-\-size\fP=\-1
Size of volume in GiB.
.TP
\fB\-\-snapshot\-factor\fP=1
Optional: Amount of storage to allocate for snapshot support.
Must be greater 1.0.
For example if a 10TiB volume requires 5TiB of snapshot storage, then snapshot\-factor would be set to 1.5.
If the value is set to 1, then snapshots will not be enabled for this volume.
.RE
.PP
\fBNote:\fP
The volume size created depends upon the underlying brick size.
For example, for a 2 way/3 way replica volume, the minimum volume size is 1GiB as the
underlying minimum brick size is constrained to 1GiB.
So, it is not possible create a volume of size less than 1GiB.
.RS
.RE
.PP
\fBExamples\fP
.RS
.PP
Create a 100GiB replica 3 volume:
.RS
.nf
$ heketi\-cli volume create \-\-size=100
.fi
.RE
.PP
Create a 100GiB replica 3 volume specifying two specific clusters:
.RS
.nf
$ heketi\-cli volume create \-\-size=100 \\
    \-\-clusters=0995098e1284ddccb46c7752d142c832,60d46d518074b13a04ce1022c8c7193c
.fi
.RE
.PP
Create a 100GiB replica 2 volume with 50GiB of snapshot storage:
.RS
.nf
$ heketi\-cli volume create \-\-size=100 \\
    \-\-snapshot\-factor=1.5 \-\-replica=2
.fi
.RE
.PP
Create a 100GiB distributed volume
.RS
.nf
$ heketi\-cli volume create \-\-size=100 \-\-durability=none
.fi
.RE
.PP
Create a 100GiB erasure coded 4+2 volume with 25GiB snapshot storage:
.RS
.nf
$ heketi\-cli volume create \-\-size=100 \-\-durability=disperse \\
    \-\-snapshot\-factor=1.25
.fi
.RE
.PP
Create a 100GiB erasure coded 8+3 volume with 25GiB snapshot storage:
.RS
.nf
$ heketi\-cli volume create \-\-size=100 \-\-durability=disperse \\
    \-\-snapshot\-factor=1.25 \\
    \-\-disperse\-data=8 \-\-redundancy=3
.fi
.RE
.RE
.RE
.PP
\fBheketi\-cli volume delete <VOLUME-ID>\fP
.RS
Deletes the volume
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli volume delete 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli volume expand --expand-size=<SIZE> --volume=<VOLUME-ID>\fP
.RS
Expand a volume
.PP
\fBOptions\fP
.RS
.TP
\fB\-\-expand\fP=""
Amount in GiB to add to the volume
.TP
\fB\-\-volume\fP=""
Id of volume to expand
.RE
.PP
\fBExample\fP
.RS
.PP
Add 10GiB to a volume:
.RS
.nf
$ heketi\-cli volume expand \-\-volume=60d46d518074b13a04ce1022c8c7193c
    \-\-expand\-size=10
.fi
.RE
.RE
.RE
.PP
\fBheketi\-cli volume info  <VOLUME-ID>\fP
.RS
Retrieves information about volume
.PP
 \fBExample\fP
.RS
.nf
$ heketi-cli volume info 886a86a868711bef83001
.fi
.RE
.RE
.PP
\fBheketi\-cli volume list\fP
.RS
Lists the volumes managed by Heketi
.PP
\fBExample\fP
.RS
.nf
$ heketi-cli volume list
.fi
.RE
.RE
.PP
.SH GLOBAL OPTIONS
.TP
\fB\-\-json\fP[=false]
Print response as JSON
.TP
\fB\-\-secret\fP=""
Secret key for specified user.
Can also be set using the environment variable HEKETI\_CLI\_KEY.
.TP
\fB\-s\fP, \fB\-\-server\fP=""
Heketi server.
Can also be set using the environment variable HEKETI\_CLI\_SERVER.
.TP
\fB\-\-user\fP=""
Heketi user.
Can also be set using the environment variable HEKETI\_CLI\_USER.
.TP
\fB\-v\fP, \fB\-\-version\fP[=false]
Print version.
.PP
.SH EXAMPLES
.PP
.SS List Volumes
.PP
Specify the Heketi server to contact using an environment variable
and list the volumes.
.RS
.nf
$ export HEKETI\_CLI\_SERVER=http://localhost:8080
$ heketi\-cli volume list
.fi
.RE
.PP
.SS Create a Volume
.PP
Create a 4 GiB volume.
.RS
.nf
$ heketi\-cli volume create --size 4
.fi
.RE
.PP
.SS Create an Arbiter Volume
.PP
Create a 4 GiB volume that uses the arbiter feature.
.RS
.nf
$ heketi\-cli volume create --size 4 --gluster-volume-options='user.heketi.arbiter true'
.fi
.RE
.SH COPYRIGHT
.nf
Copyright (c) 2015-2018 The heketi Authors
.fi
